Compose 配置速查

compose.yaml 常用配置项与 docker compose 子命令的速查表，写给已经写过几份 compose 文件、临时想不起某个字段写法时翻一翻的场景。字段的详细讲解见本系列「Docker Compose」一章。

配置项一览

服务定义（services 下的字段）

配置项	作用	示例
image	指定服务使用的镜像，省略标签时默认 latest	image: nginx:1.27
build	从 Dockerfile 构建镜像，可写上下文路径或展开为对象	build: . 或 build: { context: ., dockerfile: Dockerfile }
container_name	指定容器名，不带项目名前缀；多副本时会冲突，一般不写	container_name: my-web
ports	端口映射，格式 宿主机端口:容器端口；只写容器端口则宿主机随机分配	- "8080:80"
volumes	挂载数据卷或目录，格式 宿主机路径:容器路径[:选项]；命名卷需先声明	- db-data:/var/lib/mysql、./html:/usr/share/nginx/html:ro
environment	设置容器内环境变量，可写列表或键值对	- TZ=Asia/Shanghai 或 MYSQL_ROOT_PASSWORD: secret
env_file	从文件批量读取环境变量，优先级低于 environment	env_file: .env
command	覆盖镜像默认的 CMD	command: redis-server --appendonly yes
entrypoint	覆盖镜像默认的 ENTRYPOINT	entrypoint: /docker-entrypoint.sh
restart	重启策略：no、always、on-failure、unless-stopped	restart: unless-stopped
depends_on	控制启动顺序，配合 condition: service_healthy 可等待健康检查通过	depends_on: { db: { condition: service_healthy } }
healthcheck	健康检查，字段有 test/interval/timeout/retries/start_period	test: ["CMD", "pg_isready", "-U", "postgres"]
profiles	给服务打标签，只有激活对应 profile 才会启动	profiles: ["debug"]
networks	指定服务加入的网络，不写则进默认网络	networks: [frontend, backend]
deploy.resources	限制 CPU、内存等资源（Swarm 之外的场景也支持 limits）	limits: { cpus: "0.5", memory: 512M }

build 与 image 同时写

两者同时出现时，Compose 会用 build 构建镜像，并以 image 指定的名字和标签保存，方便后续 push 或复用。

顶层字段

配置项	作用	示例
name	项目名，决定生成的容器、网络、卷名字的前缀；不写取所在目录名	name: myapp
services	必填，定义一个个服务，下面每个 key 就是一个容器	services: { web: ... }
networks	声明自定义网络，可选驱动、子网等配置	networks: { backend: { driver: bridge } }
volumes	声明命名数据卷，供服务的 volumes 引用	volumes: { db-data: {} }
secrets	声明敏感数据文件，挂载进容器的 /run/secrets 目录	secrets: { db-password: { file: ./db-password.txt } }
configs	声明配置文件，挂载进容器供服务读取	configs: { nginx-conf: { file: ./nginx.conf } }

提示

服务里引用的 secrets 和 configs 必须在顶层先声明，否则 up 时会直接报错。

常用配置示例

一个「Web 服务 + 数据库」的常用骨架，字段都带了注释：

name: myapp                # 项目名，决定资源名前缀；不写默认取目录名

services:
  web:
    image: nginx:1.27      # 使用的镜像
    container_name: myapp-web  # 固定容器名（可选，一般不写）
    restart: unless-stopped    # 重启策略：除非手动停止，否则一直拉起
    ports:
      - "8080:80"          # 宿主机 8080 映射到容器 80
    volumes:
      - ./html:/usr/share/nginx/html:ro  # 挂载本地目录，ro 表示只读
    environment:
      TZ: Asia/Shanghai    # 容器内环境变量
    depends_on:
      db:
        condition: service_healthy  # 等 db 健康检查通过后再启动
    networks:
      - backend            # 加入自定义网络

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: secret
    env_file:
      - .env               # 从文件批量读取环境变量
    volumes:
      - db-data:/var/lib/postgresql/data  # 命名卷持久化数据
    healthcheck:           # 健康检查：每 10 秒探测一次
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

networks:
  backend:                 # 声明自定义桥接网络
    driver: bridge

volumes:
  db-data:                 # 声明命名卷，交给 Docker 管理

需要本地构建镜像的服务骨架：

services:
  app:
    build:                 # 从 Dockerfile 构建镜像
      context: .           # 构建上下文目录
      dockerfile: Dockerfile
    image: myapp:dev       # 构建出的镜像以这个名字保存
    command: npm run dev   # 覆盖镜像默认 CMD
    profiles:
      - dev                # 只在 --profile dev 激活时启动
    ports:
      - "3000:3000"
    deploy:
      resources:
        limits:
          cpus: "0.5"      # 最多使用半个 CPU
          memory: 512M     # 内存上限 512 MB

命令速查

日常高频子命令一览，完整用法可加 --help 查看：

命令	作用	示例
up	创建并启动所有服务，-d 后台运行，--build 强制重建镜像	docker compose up -d
down	停止并删除容器、网络；-v 连同命名卷一起删（数据会丢）	docker compose down
ps	查看项目内容器状态，-a 含已停止的	docker compose ps
logs	查看日志，-f 持续跟踪，--tail 只看末尾几行	docker compose logs -f web
exec	进入运行中的容器执行命令	docker compose exec web sh
run	以某个服务为模板启动一次性容器	docker compose run --rm web sh
build	构建或重新构建服务镜像	docker compose build --no-cache
pull / push	拉取 / 推送服务用到的镜像	docker compose pull
start / stop / restart	启动、停止、重启已有容器，不重建	docker compose restart web
config	打印变量替换、合并后的最终配置	docker compose config
config --quiet	只校验语法不输出内容，适合 CI 或写文件后自查	docker compose config --quiet
images	列出项目用到的镜像	docker compose images
top	查看容器内运行的进程	docker compose top
stats	实时查看容器资源占用	docker compose stats
watch	监听代码变化自动同步或重建，需配置 develop.watch	docker compose watch

写完文件先校验再启动

改完 compose.yaml 先跑 docker compose config --quiet 校验语法，再跑 docker compose config 检查变量替换结果，比直接 up 报错好排查得多。

备注

除 config、version 外，大部分子命令需要在 compose 文件所在目录执行；不在该目录时用 -f 指定文件，例如 docker compose -f /opt/myapp/compose.yaml up -d。